home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / tjgold.zip / INSTALL.004 / FGUSER19.TXT < prev    next >
Text File  |  1995-05-29  |  11KB  |  285 lines
  1.                            Date & Time Management
  2.  
  3.                                   "Poetic justice with her lifted scale;
  4.                                    where, in nice balance, truth with
  5.                                    gold she weighs, and solid pudding
  6.                                    against empty praise."
  7.                                                 A Pope, The Duncied 1728
  8.  
  9. Introduction
  10.  
  11.           Date manipulation has always been a problem for computer
  12.      programmers. If only there were ten days in a week, ten weeks in a
  13.      year, and ten years in a century! Date mathematics is just plain
  14.      clumsy when you think of dates in terms of days, months, and years.
  15.      Try computing the date one hundred days after February 20, 1965!
  16.      Not so easy.
  17.  
  18.           Date mathematics is greatly simplified when you convert dates
  19.      into their Julian form. Over the centuries, many mathematicians
  20.      have devised methods of accurately computing dates. Most modern
  21.      computer systems (including this toolkit!) use the Julian system.
  22.      The Julian period was devised in 1582 by Joseph Scaliger, and was
  23.      named after his father Julian (not after the Julian calendar). The
  24.      Julian system assigns each day its own sequential number. Day 1
  25.      began at noon, January 1, 4713 BC. Every day since that time has
  26.      its own sequential number, thus, February 11, 1991 is Julian period
  27.      2448299.
  28.  
  29.           The GoldDate Unit provides a variety of functions for
  30.      converting dates to and from Julian format. To compute the date one
  31.      hundred days after February 20, 1956, you would convert the date to
  32.      Julian, add one hundred to it, and convert it back to a string.
  33.      This can be achieved with the following compound statement using
  34.      toolkit functions.
  35.  
  36.           FancyDateStr(GregToJul(2,20,1956)+100,true,true);
  37.  
  38.           This uses the function GregToJul to convert Month, Day, and
  39.      Year to a Julian period. A hundred is then added to it, and this
  40.      value is passed to the function FancyDateStr, which returns a text
  41.      string showing the date represented by the Julian period. In this
  42.      example, the following date would be returned:
  43.  
  44.           Wednesday May 30, 1956
  45.  
  46.           Gold supports dates in eight different formats. Using M, D,
  47.      and Y to represent months, days, and years respectively, the
  48.      supported formats are:
  49.  
  50.           MMDDYY
  51.           MMDDYYYY
  52.           MMYY
  53.           MMYYYY
  54.           DDMMYY
  55.           DDMMYYYY
  56.           YYMMDD
  57.           YYYYMMDD
  58.  
  59.           Many of the GoldStr functions need to know in which format the
  60.      date strings are, and so the unit includes the enumerated type
  61.      gDate, which (not surprisingly) has the following members: MMDDYY,
  62.      MMDDYYYY, MMYY, MMYYYY, DDMMYY, DDMMYYYY, YYMMDD, and YYYYMMDD.
  63.  
  64.           If you plan to delve into ancient history with your date
  65.      calculations, you need to be aware of some strange facts. For
  66.      example, different countries decided to drop certain days to adjust
  67.      for inaccuracies in the lunar calendar. In 1752, the British
  68.      decreed that the following September 2nd would be September 14th.
  69.      Further back in 1582, Pope Gregory XIII (of Gregorian calendar
  70.      fame!) decreed that October 4th would become October 15th. In 1793
  71.      the French ... well, you get the idea. For a good summary of these
  72.      calendar aberrations, refer to any copy of The World Almanac and
  73.      Book of Facts.
  74.  
  75. Date Methods
  76.  
  77.      The GoldDate Unit includes the following routines:
  78.  
  79.      Date:string;
  80.  
  81.           Returns the system date nicely formatted. The string appears
  82.      as; the Day of Week and Month spelled out followed by the Day, and
  83.      Year.
  84.  
  85.      GregtoJul(M,D,Y:longint):longint;
  86.  
  87.      Returns the Julian value (a longint) of a Gregorian date.
  88.  
  89.      JultoGreg(Jul:longint; var M,D: word; var Y:longint);
  90.  
  91.      Converts a Julian value to its Gregorian equivalent.
  92.  
  93.      Day(DStr:string;Format:gDate):word;
  94.  
  95.      Returns the day portion of a date string.
  96.  
  97.      Month(DStr:string;Format:gDate):word;
  98.  
  99.      Returns the month portion of a date string.
  100.  
  101.      Year(DStr:string;Format:gDate):word;
  102.  
  103.      Returns the year portion of a date string.
  104.  
  105.      StrtoJul(DStr:string;Format:gDate):longint;
  106.  
  107.      Converts a date string to its Julian equivalent.
  108.  
  109.      DOWNum(DStr:string;Format:gDate):byte;
  110.  
  111.           Returns a byte indicating the day of the week representative
  112.      of a date string. 0 = Sunday, 1 = Monday, etc .....
  113.  
  114.      DOWStr(DayByte:byte): string;
  115.  
  116.           Returns the day of the week, in string form, represented by
  117.      DayByte. 0 = Sunday, 1 = Monday, etc.....
  118.  
  119.      DOWJul(Jul:longint):byte;
  120.  
  121.           Returns a byte indicating the day of the week representing the
  122.      Julian value specified. 0 = Sunday, 1 = Monday, etc .....
  123.  
  124.      GregtoStr(M,D,Y:longint;Format:gDate):string;
  125.  
  126.           Returns a date string representing the dates indicated by M,
  127.      D, and Y in the form of the enumerated Format.
  128.  
  129.      JultoStr(Jul:longint;Format:gDate):string;
  130.  
  131.           Returns a date string in the specified format representing the
  132.      Julian date indicated by Jul.
  133.  
  134.      TodayinJul:longint;
  135.  
  136.           Returns a longint value representing the system date in Julian
  137.      form.
  138.  
  139.      ValidDate(M,D,Y:longint):boolean;
  140.  
  141.           Returns TRUE if the values passed actually equate to a true
  142.      date. Each value is validated for proper month, day, and year,
  143.      including leap years.
  144.  
  145.      ValidDateStr(DStr:string;Format:gDate):boolean;
  146.  
  147.           Returns TRUE if the date string actually equals a true date.
  148.      Each value of the date string is validated for proper month, day,
  149.      and year, including leap years.
  150.  
  151.      StripDateStr(DStr:string;Format:gDate):string;
  152.  
  153.      Returns a date string with the date separators removed.
  154.  
  155.      FancyDateStr(Jul:longint; Long,Day:boolean):string;
  156.  
  157.           Returns a nicely formatted string representing the indicated
  158.      Julian value. The string is returned in the form of Day-of-week and
  159.      Month spelled out followed by the day and year as numbers.
  160.  
  161.      RelativeDate(DStr:string;Format:gDate;Delta:longint):string;
  162.  
  163.           Returns a date string that has been adjusted by the number of
  164.      days indicated by Delta. This may be a positive or negative number
  165.      of days.
  166.  
  167.      RelativeDateYMD(DStr:string;Format:gDate; Y,M,D:longint):string;
  168.  
  169.           Returns a date string that has been adjusted by the number of
  170.      years, months, and days. Each offsetting element has the ability to
  171.      be positive or negative.
  172.  
  173.      StartOfYear(Jul:longint):longint;
  174.  
  175.           Returns the Julian value of January 1st in the year of the
  176.      date passed.
  177.  
  178.      EndOfYear(Jul:longint):longint;
  179.  
  180.           Returns the Julian value of December 31st in the year of the
  181.      date passed.
  182.  
  183.      DateFormat(Format:gDate):string;
  184.  
  185.           The date format that is passed must be a member of the
  186.      enumerated type, gDate. If Format is valid, a string representation
  187.      of the date format is returned, otherwise a null string will be
  188.      returned.
  189.  
  190.      UnformattedDate(InDate:string):string;
  191.  
  192.      Strips all non-numeric characters.
  193.  
  194. Time Routines
  195.  
  196.           Even though the date routines are extremely powerful and offer
  197.      the developer a great deal of flexibility, we thought that a
  198.      complement of time routines was in order. They follow in much the
  199.      same fashion, offering the same power and flexibility within a 24
  200.      hour period.
  201.  
  202.           Like the date routines, many of the time routines require that
  203.      you specify which time format to use. The enumerated type gTime
  204.      contains the following members: HHMMSS, HHMM.
  205.  
  206.      Time:string;
  207.  
  208.           Returns the system time in a nicely formatted string. The time
  209.      string uses a 12 hour clock and is appended with an a.m. or p.m.
  210.  
  211.      Clock;
  212.  
  213.           Writes the system time to the screen at a predetermined
  214.      location. Defined within the GoldDate Unit are two variables,
  215.      DateVars.ClockX and DateVars.ClockY which determine the location
  216.      that the system time will be written.
  217.  
  218.      Hour(TStr:string;Format:gTime):word;
  219.  
  220.      Returns the hour portion of the specified time string.
  221.  
  222.      Minute(TStr:string;Format:gTime):word;
  223.  
  224.      Returns the minute portion of the specified time string.
  225.  
  226.      Second(TStr:string;Format:gTime):word;
  227.  
  228.      Returns the second portion of the specified time string.
  229.  
  230.      TimeStrToLong(TStr:string;Format:gTime):longint;
  231.  
  232.           Returns a longint value representing the number of seconds
  233.      since midnight until the specified time string.
  234.  
  235.      LongToTimeStr(Secs:longint;Format:gTime;AmPm,Mltry:boolean):string;
  236.  
  237.           Returns a time string in the specified format that represents
  238.      the specified number of seconds since midnight. An optional A.M. or
  239.      P.M. may be appended, also the time may optionally be returned in
  240.      military time.
  241.  
  242.      NowInLong:longint;
  243.  
  244.           Returns the number of seconds since midnight. This is based on
  245.      the system time.
  246.  
  247.      ValidTime(Hr,Mn,Sc:longint;Format:gTime;Mltry:boolean):boolean;
  248.  
  249.           Returns TRUE if Hr, Mn, and Sc are all valid time values. You
  250.      must specify the time format and whether or not you are using
  251.      military time.
  252.  
  253.      ValidTimeStr(TStr:string;Format:gTime;Mltry:boolean):boolean;
  254.  
  255.           Returns TRUE if the specified time string is completely valid.
  256.      You must specify the time format and whether or not you are using
  257.      military time.
  258.  
  259.      StripTimeStr(TStr:string;Format:gTime):string;
  260.  
  261.      Removes all non-numeric characters from the specified time string.
  262.  
  263.      TimeToLong(H,M,S:word):longint;
  264.  
  265.           Converts the hour, minute and second specified to the number
  266.      of seconds since midnight.
  267.  
  268.      TimeFormat(Format:gTime):string;
  269.  
  270.           The time format that is passed must be a member of the
  271.      enumerated type, gTime. If Format is valid, a string representation
  272.      of the Time format is returned, otherwise a null string will be
  273.      returned.
  274.  
  275.      TimeDiff(StartTime, StopTime: longint): longint;
  276.  
  277.           Returns a longint value representing the number of seconds
  278.      between StartTime and StopTime. If StartTime is greater than
  279.      StopTime, the difference is spanned over midnight.
  280.  
  281.      LastDateError:integer;
  282.  
  283.      Returns the code of the last error generated by a GoldDate routine
  284.  
  285.